<HTML><HEAD><TITLE>library(coverage)</TITLE></HEAD><BODY>
[ <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]<H1>library(coverage)</H1>
Tool for obtaining code coverage information
<H2>Predicates</H2>
<BLOCKQUOTE>
<DL>
<DT><A HREF="ccompile-1.html"><STRONG>ccompile(+File)</STRONG></A></DT>
<DD>Compile a file, inserting code coverage counters</DD>
<DT><A HREF="ccompile-2.html"><STRONG>ccompile(+File, +OptionList)</STRONG></A></DT>
<DD>Compile a file, inserting code coverage counters</DD>
<DT><STRONG>point(?)</STRONG></DT>
<DD>No description available</DD>
<DT><STRONG>print_counters</STRONG></DT>
<DD>No description available</DD>
<DT><A HREF="reset_counters-0.html"><STRONG>reset_counters</STRONG></A></DT>
<DD>Reset all the coverage counters to zero</DD>
<DT><A HREF="result-0.html"><STRONG>result</STRONG></A></DT>
<DD>Pretty-print all files with code coverage results</DD>
<DT><A HREF="result-1.html"><STRONG>result(+File)</STRONG></A></DT>
<DD>Pretty-print a file, including any code coverage results</DD>
<DT><A HREF="result-2.html"><STRONG>result(+File, +OptionList)</STRONG></A></DT>
<DD>Pretty-print a file, including any code coverage results</DD>
</DL>
</BLOCKQUOTE>
<H2>Description</H2>
<P>
	This is a tool for obtaining code coverage information, i.e.
	information about which points in the code were executed how
	often during a particular run of the program.
</P><P>
	The usage is as follows:
	<OL>
	<LI>Load the coverage library
	<PRE>
	?- lib(coverage).
	</PRE>
	<LI>Compile your program with the coverage compiler
	<PRE>
	?- coverage:ccompile(my_program).
	</PRE>
	<LI>Run the query which you want to examine
	<PRE>
	?- my_query(X,Y,Z).
	</PRE>
	<LI>Generate an html file containing the results. E.g. the following
	will create the result file coverage/my_program.html:
	<PRE>
	?- coverage:result(my_program).
	</PRE>
	<LI>View the result file using any browser. The result file
	contains a pretty-printed form of the source, annotated with
	the values of the code coverage counters.
	</OL>
</P><P>
	By default, code coverage counters are inserted before and after
	every subgoal in the code. For instance, in the clause
<PRE>
	p :- q, r, s.
</PRE>
	four counters would be inserted: before the call to q, between
	q and r, between r and s, and after s:
<PRE>
	p :- point(1), q, point(2), r, point(3), s, point(4).
</PRE>
	This is the most precise form provided. The counter values do not
	only show whether all code points were reached, they also show whether
	subgoals ever failed or aborted (in that case the counter before
	a subgoal will have a higher value than the counter after it).
	For example, the result of running the above code may look like:
<PRE>
	p :- <span style="color:black; font-weight:bold; background-color:limegreen"> 43 </span> q, <span style="color:black; font-weight:bold; background-color:limegreen"> 25 </span> r, <span style="color:black; font-weight:bold; background-color:limegreen"> 25 </span> s <span style="color:black; font-weight:bold; background-color:red"> 0 </span>.
</PRE>
	which would indicate that q was called 43 times, but succeeded
	only 25 times, r was called 25 times and succeeded always, and
	s was called 25 times and never succeeded.  Coverage counts of
	zero are displayed in red because they indicate unreached code.
</P><P>
	If one is only interested in knowing whether all code was covered,
	it is not necessary to have all these counters. point(1) and point(4)
	are enough to know whether q, r and s were successfully executed.
	The option <B>blocks_only</B> implements this: counters only
	get inserted at the beginning and at the end of conjunctions
	(comma-separated goal sequences), i.e. in the example:
<PRE>
	p :- point(1), q, r, s, point(4).
</PRE>
	For big programs, the presence of counters at the end of
	clauses can cause problems because they prevent tail-recursion
	optimization and may lead to stack overflows.  If that should
	be the case, exit-counters can be disabled by setting the
	<B>exit_counters</B> option to <B>off</B>, leading to the following
	incomplete instrumentation:
<PRE>
	p :- point(1), q, point(2), r, point(3), s.
</PRE>
</P><P>
	Note on the analysis of large, structured applications: 
	Larger applications often consist of several modules which get
	compiled implicitly through use_module/1 directives.  In this
	case, the module(s) that one wants to compile in coverage mode
	can be either compiled with ccompile/1 in advance (before
	loading the main application module), or afterwards (in which
	case ccompile/1 will replace the previously compiled normal
	code with coverage-code).
</P><P>
	Limitation: The current implementation cannot deal with multiple
	(non-module) files that are ccompiled into the same module.
</P>
<H2>About</H2><UL COMPACT>
<LI><STRONG>Author: </STRONG>Joachim Schimpf, based on ideas by Helmut Simonis
<LI><STRONG>Copyright &copy; </STRONG>Cisco Systems, Inc.
<LI><STRONG>Date: </STRONG>$Date: 2009/02/19 06:09:22 $
</UL>
<HR>Generated from coverage.eci on 2009-05-27 01:25
</BODY></HTML>
